@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-auth-actions.md

@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/.agents/skills/profiles/react/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/.agents/skills/profiles/springboot/README.md

@@ -0,0 +1,10 @@
+# Spring Boot Profile Skills
+
+此目录存放 Spring Boot profile 专属技能。
+
+当前已规划（待实现）的技能：
+
+- `create-controller` — 按团队规范创建 Controller 及 DTO
+- `create-service` — 按团队规范创建 Service 与实现类
+- `create-repository` — 按团队规范创建 Repository / Mapper
+- `create-entity` — 按团队规范创建 Entity / Domain 对象

package/.agents/skills/profiles/vue/create-api/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: create-api
+description: 指导在 Vue 3 项目中按团队规范创建和维护 HTTP 接口，包括类型定义、请求封装、命名约定与错误处理。当前端需要新增或调整 API 时使用本技能。
+compatibility: Requires a local Vue project workspace and the repository's API/rule conventions under .agents/rules/.
+---
+
+# 创建与维护 API
+
+## 目录结构
+
+```text
+src/api/<name>.ts                # 请求函数（按业务模块拆分）
+src/api/types/<name>.ts     # 请求/响应类型定义
+```
+
+所有请求函数集中在 `src/api/` 下按模块管理，禁止在组件或 store 中直接调用 `request`。
+
+---
+
+## 创建步骤
+
+### 1. 定义类型
+
+```ts
+// src/api/types/banner.ts
+export interface Banner {
+  id: number;
+  title: string;
+  imageUrl: string;
+  status: number;
+}
+
+export interface GetBannerListParams {
+  page: number;
+  pageSize: number;
+  status?: number;
+}
+
+export interface GetBannerListResult {
+  list: Banner[];
+  total: number;
+}
+
+export type CreateBannerParams = Pick<Banner, 'title' | 'imageUrl'>;
+export type UpdateBannerParams = CreateBannerParams & { id: number };
+```
+
+类型严格依据接口文档（如 Apifox），禁止凭空创造字段。
+
+### 2. 创建请求函数
+
+```ts
+// src/api/banner.ts
+import { request } from '@koi-design/vix-tools';
+import type {
+  GetBannerListParams,
+  GetBannerListResult,
+  CreateBannerParams,
+  UpdateBannerParams,
+} from './types/banner';
+
+export function getBannerListApi(data: GetBannerListParams): Promise<GetBannerListResult> {
+  return request({ url: '/api/banner/page', method: 'post', data });
+}
+
+export function getBannerDetailApi(id: number): Promise<Banner> {
+  return request({ url: `/api/banner/${id}`, method: 'get' });
+}
+
+export function createBannerApi(data: CreateBannerParams): Promise<void> {
+  return request({ url: '/api/banner', method: 'post', data });
+}
+
+export function updateBannerApi(data: UpdateBannerParams): Promise<void> {
+  return request({ url: `/api/banner/${data.id}`, method: 'put', data });
+}
+
+export function deleteBannerApi(id: number): Promise<void> {
+  return request({ url: `/api/banner/${id}`, method: 'delete' });
+}
+```
+
+---
+
+## 命名约定（NON-NEGOTIABLE）
+
+`getXxxListApi` / `getXxxDetailApi` / `createXxxApi` / `updateXxxApi` / `deleteXxxApi`
+
+- 统一使用 `Api` 后缀，区分接口函数与业务函数
+- **禁止** `fetchXxx` 等前缀
+
+## 错误处理（NON-NEGOTIABLE）
+
+- 接口错误由 `requestConfig` 统一处理，业务代码中**禁止重复** `message.error` 等提示
+- 业务侧只处理成功逻辑及前端自身校验错误
+
+---
+
+## 快速检查清单
+
+- [ ] 类型在 `src/api/types/<name>.ts`，请求在 `src/api/<name>.ts`？
+- [ ] 命名符合 `getXxxApi` / `createXxxApi` / `updateXxxApi` / `deleteXxxApi`？
+- [ ] 使用 `import { request } from '@koi-design/vix-tools'`？
+- [ ] 未重复处理接口错误？
+- [ ] 类型与接口文档一致？

package/.agents/skills/profiles/vue/create-component/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: create-component
+description: 指导在 Vue 3 项目中按团队规范创建和拆分 SFC 组件，包括目录结构、文件命名、样式与主题变量使用。当前端需要新增或重构组件时使用本技能。
+compatibility: Requires a local Vue project workspace and the repository's component/style conventions under .agents/rules/.
+---
+
+# 创建与拆分 Vue 组件
+
+## 组件放在哪里？
+
+- **通用组件**（跨页面复用）：`src/components/<component-name>/index.vue + types.ts + style.module.scss`
+- **页面级组件**（只在单页使用）：`src/views/<page>/components/<component-name>/`
+- 目录名 `kebab-case`，组件引用名 `PascalCase`
+
+---
+
+## 创建步骤
+
+### 1. 定义类型（types.ts）
+
+```ts
+// src/components/user-avatar/types.ts
+export interface UserAvatarProps {
+  src: string
+  size?: number
+}
+export interface UserAvatarEmits {
+  (e: 'click', event: MouseEvent): void
+}
+```
+
+### 2. 编写 SFC（index.vue）
+
+```vue
+<!-- src/components/user-avatar/index.vue -->
+<script setup lang="ts">
+import type { UserAvatarProps, UserAvatarEmits } from './types'
+import styles from './style.module.scss'
+
+withDefaults(defineProps<UserAvatarProps>(), { size: 40 })
+defineEmits<UserAvatarEmits>()
+</script>
+
+<template>
+  <img :class="styles.avatar" :src="src" :width="size" :height="size" @click="$emit('click', $event)" />
+</template>
+```
+
+### 3. 样式（style.module.scss）
+
+```scss
+.avatar {
+  border-radius: 50%;
+  object-fit: cover;
+  border: 1px solid var(--color-border);        // 必须使用主题变量
+  background-color: var(--color-bg-container);   // 禁止硬编码颜色
+}
+```
+
+---
+
+## 核心规则
+
+- 必须使用 `<script setup lang="ts">`，通过 `defineProps` / `defineEmits` / `defineSlots` 声明接口
+- 样式使用 CSS Modules（`style.module.scss`）或 `<style scoped>`，颜色必须用主题变量
+- 单个 `.vue` 文件不超过 **400 行**，超过时拆分子组件
+- 一个组件聚焦单一职责
+
+---
+
+## 快速检查清单
+
+- [ ] 组件放在了正确位置（通用 vs 页面级）？
+- [ ] 使用了 `<script setup lang="ts">` + defineProps/defineEmits？
+- [ ] 样式使用 CSS Modules 或 scoped，颜色用主题变量？
+- [ ] 文件不超过 400 行？