@ai0x0/utils 0.0.32 → 0.0.33

package/.agents/skills/ai0x0-utils/backend/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: ai0x0-utils/backend
+description: Scaffold Next.js App Router CRUD endpoints and drizzle-orm(pg) tables with `@ai0x0/utils`. Use when a project needs standard list/get/create/update/delete routes backed by drizzle-orm + zod + next-rest-framework, auto-injected base fields (id / creatorId / createdAt…), paginated list queries with joins, or ready-to-use select/insert/update Zod schemas. Pair with the `create-next-rest-framework-api` skill — this skill replaces hand-written `routeOperation(...).input(...).outputs(...).handler(...)` chains with a declarative factory API exposed inside `next-rest-framework`'s `route({...})`.
+---
+
+# @ai0x0/utils Backend
+
+Declarative CRUD factory on top of `next-rest-framework` v6, `drizzle-orm/pg-core`, `drizzle-zod`, and `zod` v4. Each factory returns a `RouteOperationDefinition<Method>` so it plugs directly into `route({ … })` from next-rest-framework.
+
+## Related Project Skills
+
+This backend factory skill pairs with the packaged project skills:
+
+- `nextjs` — route placement, App Router boundaries, OpenAPI generation, file splitting.
+- `antd` — frontend forms, ProTable/ModalForm, request flow, token styling.
+- `cloudflare` — OpenNext, Workers, Hyperdrive, Neon, deploy/runtime checks.
+
+When a CRUD change spans backend and frontend, use this skill for factories and schemas, then apply `nextjs` for routing/client generation and `antd` for the admin page.
+
+## Workflow
+
+1. Create a shared options module (once per project) that pre-binds `{ db, getSession }` to every operation factory (see "Project Setup" below). Route files never import `db`/`getSession` directly.
+2. For each domain entity, place a `table.ts` next to an `index.ts`:
+   - `table.ts` — call `createTableSchema({ name, columns })` and re-export `table` only.
+   - `index.ts` — compose the zod schemas (`insertXxxSchema`, `selectXxxSchema`, `updateXxxSchema`, `queryXxxSchema`, `queryListXxxSchema`, `queryListSelectXxxSchema`). Extend with `.merge(z.object(...))` when the business exposes non-column fields (tags, computed columns).
+3. Author the CRUD `route.ts` by wrapping the pre-bound operations inside next-rest-framework's `route({...})`. Name each operation key descriptively — it is the OpenAPI `operationId`.
+4. Drop down to raw `routeOperation(...)` (via the `create-next-rest-framework-api` skill) when the endpoint is non-CRUD (auth, webhooks, streaming, multi-status) or needs custom `TypedNextResponse` unions.
+5. Reuse action-level helpers (`createGetAction`, `createGetListAction`, etc.) inside server actions, cron jobs, queue consumers, or the raw-`routeOperation` handlers — same API, no request wrapping.
+
+## ESLint-Aware Defaults
+
+The bundled ESLint preset treats every custom rule as an error. Backend examples should follow these defaults:
+
+- Use `async/await`; do not use `.then()`.
+- Use meaningful variable names; avoid single-letter names except `_`, loop counters, and generic type parameters.
+- Use braces for every control-flow block because `curly` is enabled as `error`.
+- Keep route files thin. Put reusable logic in `utils/actions/<resource>.ts` instead of exporting helpers from `route.ts`.
+- For files with 150+ lines, add the three-line `===` section divider blocks described in the `nextjs` skill.
+- Avoid `try/catch` in route handlers; use `onError` or the factory default error handling.
+
+## Project Setup
+
+Create three files once and reuse everywhere:
+
+```ts
+// app/(backend)/db/schemas/_helper.ts — re-export + lock import path
+export {
+  createTableSchema,
+  queryListSchema,
+  listBodySchema,
+} from "@ai0x0/utils/lib/backend/schemas";
+```
+
+```ts
+// app/(backend)/utils/actions/_helper.ts — action-level helpers
+export {
+  createDeleteAction,
+  createGetAction,
+  createGetListAction,
+  createPostAction,
+  createPutAction,
+} from "@ai0x0/utils/lib/backend/actions";
+```
+
+```ts
+// app/(backend)/utils/route-operation/index.ts — pre-bind db + getSession
+import {
+  createGetOperation,
+  createPutOperation,
+  createPostOperation,
+  createDeleteOperation,
+  createGetListOperation,
+} from "@ai0x0/utils/lib/backend";
+import { db } from "@backend/db";
+import getSession from "@backend/utils/get-session";
+
+export const postOperation = createPostOperation({ db, getSession });
+export const deleteOperation = createDeleteOperation({ db, getSession });
+export const putOperation = createPutOperation({ db, getSession });
+export const getOperation = createGetOperation({ db, getSession });
+export const getListOperation = createGetListOperation({ db, getSession });
+```
+
+`getSession(req)` **must** return `{ userId?: string } | undefined` (a Promise is fine). Throwing rejects the request; returning `undefined` disables ownership checks for that call.
+
+## Factory Catalog
+
+| Export              | Purpose                    | Required options                     | Notable optional options                                                                    |
+| ------------------- | -------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `createTableSchema` | pg `Table` + 5 zod schemas | `name`, `columns`                    | `refineSchema`, `extraConfig`                                                               |
+| `getOperation`      | GET one by filters         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `byCreator`, `onSuccess`, `onError`, `summary` |
+| `getListOperation`  | GET paginated list         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`              |
+| `postOperation`     | POST create                | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`                            |
+| `putOperation`      | PUT update                 | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`               |
+| `deleteOperation`   | DELETE                     | `table`                              | `byCreator`, `onSuccess`, `onError`, `summary`                                              |
+
+## Canonical Examples
+
+### 1. Table + schemas (`table.ts` + `index.ts`)
+
+```ts
+// app/(backend)/db/schemas/agent/table.ts
+import { jsonb, text } from "drizzle-orm/pg-core";
+import { createTableSchema } from "@backend/db/schemas/_helper";
+
+export const agentColumns = {
+  name: text("name"),
+  modelId: text("model_id"),
+  tags: jsonb("tags"),
+  mcpIds: jsonb("mcp_ids"),
+};
+
+export const { table: agents } = createTableSchema({
+  name: "agents",
+  columns: agentColumns,
+});
+```
+
+```ts
+// app/(backend)/db/schemas/agent/index.ts
+import { createSelectSchema } from "drizzle-zod";
+import { z } from "zod";
+import {
+  createInsertBodySchema,
+  createUpdateBodySchema,
+  queryListSchema,
+} from "@backend/db/schemas";
+import { agents } from "./table";
+
+export { agents, agentColumns } from "./table";
+
+export const insertAgentSchema = createInsertBodySchema(agents).merge(
+  z.object({
+    mcpIds: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  }),
+);
+export const selectAgentSchema = createSelectSchema(agents).merge(
+  z.object({
+    mcpIds: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  }),
+);
+export const updateAgentSchema = createUpdateBodySchema(agents).merge(
+  z.object({
+    mcpIds: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  }),
+);
+export const queryAgentSchema = insertAgentSchema.partial();
+export const queryListAgentSchema = queryListSchema(
+  selectAgentSchema.partial().merge(
+    z.object({ tags: z.string().optional() }), // 列表里 jsonArray 以逗号分隔字符串传入
+  ),
+);
+export const queryListSelectAgentSchema = selectAgentSchema;
+```
+
+Note the two-layer shape: `queryListSchema(...)` input is the **partial of the select schema** (optionally merged with extra querystring-only fields); `bodySchema` in `getListOperation` stays as the full select schema (`queryListSelectAgentSchema`).
+
+### 2. Detail CRUD route
+
+```ts
+// app/(backend)/api/agent/route.ts
+import { route } from "next-rest-framework";
+import {
+  agents,
+  insertAgentSchema,
+  queryAgentSchema,
+  selectAgentSchema,
+  updateAgentSchema,
+} from "@backend/db/schemas";
+import {
+  deleteOperation,
+  getOperation,
+  postOperation,
+  putOperation,
+} from "@backend/utils/route-operation";
+import getSession from "@backend/utils/get-session";
+import { seedAgentData } from "@backend/utils/actions";
+
+export const { POST, GET, DELETE, PUT } = route({
+  getAgent: getOperation({
+    querySchema: queryAgentSchema,
+    bodySchema: selectAgentSchema,
+    table: agents,
+    summary: "助手详情",
+    setParams: async (req) => {
+      const { userId } = (await getSession(req)) || {};
+      await seedAgentData(userId as string);
+      return {};
+    },
+  }),
+  postAgent: postOperation({
+    bodySchema: insertAgentSchema,
+    table: agents,
+    summary: "添加助手",
+    setBody: async () => ({ tags: ["my"] }),
+  }),
+  putAgent: putOperation({
+    bodySchema: updateAgentSchema,
+    table: agents,
+    summary: "编辑助手",
+  }),
+  deleteAgent: deleteOperation({
+    table: agents,
+    summary: "删除助手",
+  }),
+});
+```
+
+### 3. List route with relations + `onSuccess` tree building
+
+```ts
+// app/(backend)/api/channel/list/route.ts
+import { route } from "next-rest-framework";
+import { eq, sql } from "drizzle-orm";
+import {
+  channels,
+  models,
+  queryListChannelSchema,
+  queryListSelectChannelSchema,
+} from "@backend/db/schemas";
+import { getListOperation } from "@backend/utils/route-operation";
+import getSession from "@backend/utils/get-session";
+import { seedChannelData } from "@backend/utils/actions/channel";
+
+export const { GET } = route({
+  getChannelList: getListOperation({
+    querySchema: queryListChannelSchema,
+    bodySchema: queryListSelectChannelSchema,
+    table: channels,
+    summary: "获取渠道列表",
+    relations: [
+      {
+        table: models,
+        sql: eq(models.channelId, channels.id),
+        select: {
+          models: sql`(
+            SELECT array_agg(DISTINCT jsonb_strip_nulls(to_jsonb(models.*)))
+            FROM ${models}
+            WHERE ${models.channelId} = ${channels.id}
+          )`,
+        },
+      },
+    ],
+    setParams: async (req) => {
+      const { userId } = (await getSession(req)) || {};
+      await seedChannelData(userId as string);
+      return {};
+    },
+    onSuccess: async (result) => {
+      // 内部字段过滤 / 映射 / 树化都写在这里
+      return result;
+    },
+  }),
+});
+```
+
+For list routes that consume `jsonb` arrays as comma-separated querystring values, add `jsonArrayFields: ["tags"]`.
+
+### 4. Escape hatch — drop to raw `routeOperation` but reuse actions
+
+When the endpoint returns multiple status shapes (e.g. 200 success + 401 unauthorized), do **not** use the CRUD factories. Call `routeOperation` directly and reuse the action helpers for the database side:
+
+```ts
+// app/(backend)/api/user/me/route.ts
+import { TypedNextResponse, route, routeOperation } from "next-rest-framework";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { db } from "@backend/db";
+import { members, selectUserSchema, teams, users } from "@backend/db/schemas";
+import { createGetAction } from "@backend/utils/actions";
+import getSession from "@backend/utils/get-session";
+
+export const { GET } = route({
+  getUserMe: routeOperation({
+    method: "GET",
+    openApiOperation: { tags: ["users"], summary: "我的信息" },
+  })
+    .outputs([
+      { status: 200, contentType: "application/json", body: selectUserSchema },
+      {
+        status: 401,
+        contentType: "application/json",
+        body: z.object({ message: z.string() }),
+      },
+    ])
+    .handler(async (req) => {
+      const { userId } = (await getSession(req)) || {};
+      const user = await createGetAction({
+        db,
+        table: users,
+        bodySchema: selectUserSchema,
+        relations: [
+          { table: members, sql: eq(members.userId, users.id) },
+          {
+            groupBy: true,
+            table: teams,
+            select: { team: teams },
+            sql: eq(teams.id, members.teamId),
+          },
+        ],
+      })({ id: userId });
+      if (!user) {
+        return TypedNextResponse.json(
+          { message: "用户不存在" },
+          { status: 401 },
+        );
+      }
+      return TypedNextResponse.json(user, { status: 200 });
+    }),
+});
+```
+
+## Built-in Conventions
+
+- **Base fields** auto-added by `createTableSchema`: `id` (uuid, pk, default random) / `creatorId` / `editorId` / `accessedAt` / `createdAt` / `updatedAt`.
+- **Ownership check**: with `byCreator: true` (default on PUT/DELETE/GET), PUT/DELETE pre-fetch the row filtered by `creatorId = session.userId` and throw `"未找到…对象，或没有权限"` if missing. Set `byCreator: false` to skip (e.g. admin endpoints).
+- **Auto injection**: POST writes `creatorId = session.userId`; PUT writes `editorId = session.userId`; GET/GET_LIST append `creatorId = session.userId` to the filter when `byCreator` is on.
+- **Date coercion**: any body field ending in `At` is passed through `dayjs(value).toDate()` before write — accept ISO strings from clients.
+- **List filtering** (all querystring values are strings):
+  - `key=a,b,c` → `IN (...)` when key ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
+  - `key=foo` where key ends with `Id` → `eq`; otherwise `ILIKE %foo%`
+  - `${anything}AtFrom` / `${anything}AtTo` → `gte` / `lte` against the matching `${anything}At` column
+  - `jsonArrayFields: ["tags"]` → `EXISTS (SELECT 1 FROM jsonb_array_elements_text(col) t WHERE t LIKE %v%)`
+- **Pagination / sort**: `current` (default `"1"`), `pageSize` (default `"10"`), `orderBy` (default `createdAt`), `orderDir` (`asc|desc`, default `desc`).
+- **Relations**: `relations: [{ table, sql, select, groupBy? }]` drives `leftJoin` + optional `groupBy(root.id, relation.id)`; `select` merges into the final `SELECT` projection and can contain raw `sql\`…\`` correlated sub-queries.
+
+## Guardrails
+
+- Always pass `insertXxxSchema` to POST, `updateXxxSchema` (has `.required({ id: true })`) to PUT, `selectXxxSchema` to GET body, `queryListSchema(selectXxxSchema.partial())` to GET_LIST query.
+- Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `onSuccess` or `setParams`.
+- Do not reuse `insertSchema` for PUT — missing `id` silently dispatches an update without a where clause.
+- `bodySchema` on list/get is the **response item** schema, not the query shape. Query shape goes in `querySchema`.
+- Do not inline `{ db, getSession }` into individual route files — always import the pre-bound `postOperation` / `getListOperation` / … from `@backend/utils/route-operation` so session/DB swaps are one-file changes.
+- `jsonb` columns declared with `jsonb(...)` carry no zod info — extend the matching insert/select schema with `.merge(z.object({ field: z.array(z.string()).optional() }))` to keep typing accurate.
+- Swallowing errors: an unhandled throw in a handler propagates to next-rest-framework as a 500. Provide `onError` for any operation exposed to untrusted clients.
+- For non-CRUD behavior (middleware chains, streaming, multipart, `TypedNextResponse` unions, RPC) stop using these factories and switch to the `create-next-rest-framework-api` skill.
+
+## Escape Hatches
+
+- Extra server-side filters — `setParams(req) => Promise<Record<string, unknown>>` on GET/GET_LIST; returned keys are merged into the filter.
+- Extra columns on write — `setBody(req) => Promise<Partial<infer<IB>>>` on POST/PUT; returned fields are merged into the body before validation runs against `bodySchema`.
+- Post-processing output — `onSuccess(data) => Promise<data>`; on GET_LIST the payload is `{ data, total }`.
+- Error rewriting — `onError(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
+
+## Imports
+
+```
+@ai0x0/utils/lib/backend                   // actions + route-operation + schemas (CJS, used by Next.js server bundle)
+@ai0x0/utils/lib/backend/actions
+@ai0x0/utils/lib/backend/route-operation
+@ai0x0/utils/lib/backend/schemas
+```
+
+ESM consumers can substitute `/es/backend/...` instead of `/lib/backend/...` when Next.js resolves the `exports` map that way; prefer `/lib/backend` in Next.js projects because the server bundle is CommonJS.
+
+## Done Criteria
+
+- Route files contain zero hand-written `{ db, getSession }` wiring; all operations come from `@backend/utils/route-operation`.
+- Each domain has a `table.ts` (columns + `createTableSchema`) and an `index.ts` (five zod schemas + re-exports).
+- Every list endpoint accepts `current / pageSize / orderBy / orderDir / *AtFrom / *AtTo` and — where applicable — `jsonArrayFields` is declared.
+- `byCreator` is explicitly set when the endpoint is admin-facing or otherwise crosses ownership boundaries.
+- Non-CRUD endpoints are implemented via raw `routeOperation` + action helpers, not by forcing a CRUD factory.
+- `next-rest-framework validate` / `generate` (from the partner skill) still pass — the factory values are plain `RouteOperationDefinition` and participate in OpenAPI generation.

package/.agents/skills/antd/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: antd
+description: Ant Design / Ant Design Pro 前端页面、表单、ProTable、ModalForm、主题 token、布局组件和 ahooks 数据流约定。新增或修改业务 UI、表单、搜索筛选、配置面板、管理后台 CRUD 页面时使用。
+metadata:
+  short-description: Ant Design 表单、页面与主题约定
+---
+
+# Ant Design 开发约定
+
+适用于基于 antd、Ant Design Pro、ProComponents、antd-style、ahooks 的业务前端。
+
+## 客户端组件与 API
+
+- 需要交互或状态的组件首行加 `"use client"`。
+- API 调用统一走 `@frontend/apis`，类型来自 `@frontend/apis/generator`。
+- 生成产物不要手改；接口或 schema 变更后重新生成 OpenAPI client。
+- 全局状态用 `unstated-next` 的 `data-store.tsx`。
+- 弹出类 UI 用 `app/(frontend)/app.tsx` 暴露的 `app`，避免 antd 静态方法告警。
+
+## 表单核心规则
+
+所有表单组件必须使用 `Form.useForm()`、ahooks/rc-field-form 的 `useForm` 或 ProComponents 内建 form 管理状态。
+
+禁止在表单场景中使用：
+
+- `useState` 直接绑定多个字段的 `value` + `onChange`
+- 裸 `useRef` 读取输入值
+- 手动拼接对象后提交
+
+适用范围：
+
+- 数据录入表单
+- 搜索 / 筛选面板
+- 聊天输入框里的多字段输入
+- 配置弹窗 / Drawer
+- 任意包含两个及以上输入控件的组件
+
+例外：
+
+- 纯展示文本
+- 单一开关 / 单选且无需校验
+- 第三方组件已经内部封装 Form
+
+ESLint 会把“同一文件里存在受控输入 `value` + `onChange`，同时使用 `useState` / `useSetState`”识别为违规表单状态管理。遇到多字段输入时，直接上 Form，不要先写本地 state 再迁移。
+
+## 表单与请求
+
+表单提交配合 `useRequest`，不要在 `onFinish` 里裸写 async/await 和 try/catch。
+
+```tsx
+const { run: submit } = useRequest(
+  async (values) => {
+    await apis.postSomething({ body: values });
+  },
+  { manual: true },
+);
+
+<Form form={form} onFinish={submit} />;
+```
+
+辅助说明文字使用 `Form.Item` 的 `help`，不要拼进 `label` 字符串。
+
+强制表单约定：
+
+- `<Form>` 必须用 `onFinish` 提交。
+- 有 `name` 的 `<Form.Item>` 必须写 `rules`，`noStyle` 例外。
+- Modal + Form 组合禁止用 `Modal.onOk` 提交，改用 `Form.onFinish`。
+- 禁止 `form.validateFields()` + 手动提交的模式。
+- 请求错误由拦截器统一处理，禁止在 `useRequest` 回调里 `message.error` / `app?.message.error`。
+
+## ProComponents CRUD 页面
+
+管理页优先使用 `ProTable` + `ModalForm`。
+
+```tsx
+"use client";
+
+import type { ActionType, ProColumns } from "@ant-design/pro-components";
+import { ModalForm, ProFormText, ProTable } from "@ant-design/pro-components";
+import apis from "@frontend/apis";
+
+const columns: ProColumns<Row>[] = [
+  { title: "名称", dataIndex: "name" },
+  {
+    title: "创建时间",
+    dataIndex: "createdAt",
+    valueType: "dateRange",
+    search: {
+      transform: (value) => ({
+        createdAtFrom: value[0],
+        createdAtTo: value[1],
+      }),
+    },
+    editable: false,
+  },
+];
+
+const Page = () => (
+  <ProTable
+    columns={columns}
+    request={async (query) => {
+      const { data } = await apis.getKeyList(query);
+      return { data: data.data, success: true, total: data.total };
+    }}
+  />
+);
+```
+
+约定：
+
+- `ProTable request` 必须返回 `{ data, success, total }`，否则分页不生效。
+- 时间范围列用 `valueType: "dateRange"` + `search.transform` 映射 `<field>From/<field>To`。
+- 图片表单列用 `renderFormItem` 接入上传组件。
+- 删除走 `Popconfirm`。
+- 提交成功后调用 `action?.reload()`。
+
+业务表单优先 ProComponents：
+
+- 禁止直接用 antd `<Modal>`，使用 `ModalForm`。
+- 禁止直接用非 `noStyle` 的 `<Form.Item>`，使用 `ProFormText` / `ProFormSelect` / `ProFormItem` 等。
+- `ProForm*` 字段组件必须设置 `rules`；容器类 `ProForm`、`ProFormGroup`、`ProFormList`、`ProFormDependency` 例外。
+- 禁止 `<Button htmlType="submit">`，通过 ProForm 的 `submitter` 配置提交按钮。
+
+## 布局与文本
+
+业务页面禁止用 `<div>` / `<span>` / `<p>` / `<h1-6>` 承载布局或文本，优先使用 antd 组件。
+
+- 布局容器 -> `Flex`
+- 纯文本 -> `Typography.Text` / `Typography.Paragraph` / `Typography.Title`
+- 次级、危险、警告、成功文本 -> `Text type="secondary|danger|warning|success"`
+- Badge、Tag、Avatar、Image、Button 等使用 antd 对应组件
+
+允许例外：
+
+- 框架或第三方组件必须的结构标签。
+- 纯 Portal / ref 挂载点。
+- SVG 内部元素。
+- antd 没有对等组件的语义标签，如必要的外链 `<a target>`。
+- 禁止 antd `<Space>` / `<Space.Compact>`，使用 `<Flex>`。
+
+Space 到 Flex 的常见替换：
+
+- `<Space direction="vertical">` -> `<Flex vertical>`
+- `<Space size={token.paddingSM}>` -> `<Flex gap={token.paddingSM}>`
+- `<Space wrap>` -> `<Flex wrap="wrap">`
+- `<Space.Compact>` -> 用 `<Flex>` 和 token 自行实现紧凑排列
+
+提交前在改动范围内检查：
+
+```bash
+rg -n "<(div|span|p|h[1-6])[ >]"
+```
+
+## 主题与样式
+
+- 使用 antd 6 + `antd-style`。
+- 顶层用 `@ant-design/nextjs-registry` 的 `AntdRegistry` 包裹，不再写 `unstable_setRender` 或自定义 `StyleRegistry`。
+- 主题色从全局 env/store 读取，开启 `cssVar: {}`。
+- 中文语言包统一在 theme 入口设置 `ConfigProvider locale={zhCN}` 和 `dayjs.locale("zh-cn")`。
+
+所有前端样式必须走 antd token，禁止硬编码视觉值：
+
+- 颜色：`#fff`、`rgb(...)`、`rgba(...)`、`hsl(...)`
+- 间距/字号/圆角：`12px`、`8px 16px`
+- 阴影：`0 2px 8px rgba(...)`
+
+推荐：
+
+```tsx
+import { createStyles } from "antd-style";
+
+const useStyles = createStyles(({ token, css }) => ({
+  card: css`
+    background: ${token.colorBgContainer};
+    color: ${token.colorText};
+    border: 1px solid ${token.colorBorderSecondary};
+    border-radius: ${token.borderRadiusLG}px;
+    padding: ${token.paddingLG}px;
+    box-shadow: ${token.boxShadowTertiary};
+  `,
+}));
+```
+
+允许例外：
+
+- `0`。
+- CSS 功能性关键字，如 `auto`、`none`、`hidden`、`pointer`、`center`、`flex`、`grid`、`relative`。
+- 条件表达式、变量、函数调用、`calc()` / `min()` / `max()` / `clamp()`。
+- `css`` 中通过 `${token.xxx}` 插值的值。
+- `100%`、`100vh`、`100vw` 等布局尺寸。
+- 第三方库强制要求的字面量，但要用中文注释说明原因。
+
+检查硬编码视觉值：
+
+```bash
+rg -n "#[0-9a-fA-F]{3,8}\\b|rgba?\\(|hsla?\\(|[0-9]+(px|rem|em)\\b"
+```
+
+## ahooks 数据流
+
+业务组件里请求、定时器、防抖、节流、生命周期、布尔状态等优先用 ahooks。
+
+| 需求               | 避免                               | 推荐                              |
+| ------------------ | ---------------------------------- | --------------------------------- |
+| 请求 / 加载 / 错误 | `useState + useEffect + try/catch` | `useRequest`                      |
+| 防抖 / 节流        | 自写 `setTimeout`                  | `useDebounceFn` / `useThrottleFn` |
+| 挂载 / 卸载        | 手写 mounted 状态                  | `useMount` / `useUnmount`         |
+| 上一个值           | 自写 ref 比较                      | `usePrevious`                     |
+| 定时器             | `setInterval` + cleanup            | `useInterval` / `useTimeout`      |
+| URL 状态           | 手写 router/searchParams           | `useUrlState`                     |
+| 布尔开关           | 多个 setter                        | `useBoolean` / `useToggle`        |
+
+业务页面 / 组件不要直接写请求型 `useEffect`。如果确实需要底层 `useEffect`，在函数上方用中文注释说明为什么 ahooks 覆盖不了。
+
+按钮请求标准链路：`manual: true` + `runAsync` + `await` + `refresh`，不要自己维护 loading、try/catch 和 toast。
+
+`useRequest` 解构时禁止使用 `run` 或 `run: alias`：
+
+```tsx
+const { runAsync: submit } = useRequest(save, { manual: true });
+
+await submit(values);
+```
+
+连续多个 `setState({ ... })` 要合并成一次：
+
+```tsx
+setState({ open: false, current: undefined });
+```
+
+## 类型与枚举
+
+- 不要手写 `"a" | "b" | "c"` 重复 OpenAPI enum。
+- `Segmented`、`Menu`、Tabs 的 value/key 使用 generator 导出的 `XxxEnum`。
+- props、state、request body 使用 generator 导出的类型。
+- 对象字面量符合接口时用 `satisfies`，不要 `as T`。
+
+## ESLint 规则对应
+
+- `require-use-form`：受控表单字段必须交给 Form 管理。
+- `require-form-convention`：Form/onFinish/rules/Modal 提交/错误提示约定。
+- `require-pro-components`：ModalForm、ProForm 字段和 submitter 约定。
+- `no-hardcoded-style`：token 样式约定。
+- `no-antd-space`：Flex 替代 Space。
+- `no-use-request-run`：`runAsync` 替代 `run`。
+- `no-consecutive-setstate`：合并连续 setState。
+
+## 前端自检
+
+- 新增/修改 UI 后跑 `pnpm exec tsc` 和 `pnpm exec eslint`。
+- 表单场景确认由 Form 管理状态。
+- ProTable request 确认返回 `total`。
+- 业务文本和布局确认使用 antd 组件。
+- 样式确认使用 token。
+- 涉及真实交互时在浏览器点一次受影响页面，确认 Console 无 error/warning。