@ai0x0/utils 0.0.31 → 0.0.33

package/.agents/skills/cloudflare/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: cloudflare
+description: Cloudflare Workers、OpenNext、Wrangler、Hyperdrive、Neon Postgres、环境变量、部署、远程迁移和线上故障排查约定。调整 Worker 构建、wrangler 配置、环境绑定、数据库连接、test/prod 发布时使用。
+metadata:
+  short-description: Cloudflare Workers 部署与运行时约定
+---
+
+# Cloudflare Workers 约定
+
+适用于通过 `@opennextjs/cloudflare` 部署到 Cloudflare Workers，并通过 Hyperdrive 连接 Neon Postgres 的 Next.js 项目。
+
+## 架构
+
+```txt
+Next.js App Router
+  -> @opennextjs/cloudflare build
+  -> Cloudflare Worker
+  -> Hyperdrive
+  -> Neon Postgres
+```
+
+本地开发通过 Wrangler 模拟 Worker 环境，`hyperdrive.localConnectionString` 指向本地 Postgres。
+
+## 本地环境
+
+```bash
+pnpm install
+cp .dev.vars.example .dev.vars
+docker compose up -d my-postgres
+pnpm db:migrate
+pnpm dev
+```
+
+关键配置：
+
+- `wrangler.jsonc` 的 `hyperdrive.localConnectionString` 是本地 PG 连接串的唯一定义点。
+- `.dev.vars` 是 Wrangler 本地 secrets，会作为 Cloudflare env binding 注入。
+- `.env.local` 只放品牌变量和 edge/proxy 必须读取的 `SESSION_SECRET`。
+- 线上 secrets 使用 `pnpm exec wrangler secret put <KEY>`。
+
+业务代码读取环境变量时，优先走项目封装的 `fileEnv` / `getCloudflareEnv()` / `getCloudflareEnvAsync()`，不要散落 `process.env`。
+
+## Worker 构建约束
+
+- 使用 `@opennextjs/cloudflare` 把 Next.js 打成 Worker。
+- Worker 免费档 gzip 产物需小于 3 MiB。
+- 管理后台重页面优先 `ssr:false` 动态加载。
+- `scripts/patch-handler.mjs` 用于剔除不适合 Worker 免费档的包或压缩产物。
+- `compatibility_flags` 必须包含 `nodejs_compat`；如果项目依赖公开 fetch 语义，也保留 `global_fetch_strictly_public`。
+- Workers 跑不了原生模块，新增依赖前确认能在 Workers/nodejs_compat 下运行。
+- `bcrypt` 用 `bcryptjs`，避免 `sharp` / `canvas` 这类原生绑定。
+
+## 数据库与 Hyperdrive
+
+- 线上数据库连接通过 `env.HYPERDRIVE.connectionString`。
+- 本地 Wrangler 会把 `wrangler.jsonc` 的 `hyperdrive.localConnectionString` 注入为 Hyperdrive binding。
+- 不要在业务代码里硬编码数据库连接串。
+- 跨账号或多环境部署时，确认目标 Worker 账号、env 和 Hyperdrive binding 匹配。
+
+本地迁移：
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+远程 Neon 迁移推荐用 drizzle migrator 跑已生成的 SQL，不直接手工改 Neon：
+
+```bash
+DRIZZLE_DATABASE_URL='postgresql://...' \
+  node -e "const{drizzle}=require('drizzle-orm/node-postgres');const{migrate}=require('drizzle-orm/node-postgres/migrator');const{Pool}=require('pg');const p=new Pool({connectionString:process.env.DRIZZLE_DATABASE_URL,ssl:{rejectUnauthorized:false}});migrate(drizzle(p),{migrationsFolder:'./app/(backend)/db/migrations'}).then(()=>p.end())"
+```
+
+## 部署命令
+
+```bash
+pnpm run deploy:test
+pnpm run deploy
+```
+
+典型脚本顺序：
+
+1. `opennextjs-cloudflare build`
+2. `node scripts/patch-handler.mjs`
+3. `wrangler deploy --env=test` 或生产 env
+
+发布前检查：
+
+- `pnpm build` 通过。
+- `pnpm exec eslint` 无错误。
+- `pnpm db:generate` 无未提交 diff，schema 与 migrations 同步。
+- 涉及 schema 变更时，migration 已推到对应 Neon 库。
+- 新增 API 已生成 `openapi.json` 和前端 client。
+- `.dev.vars.example` 同步新增 env key。
+- 已确认部署账号、分支、Worker 名称、Hyperdrive 资源和目标域名。
+
+## 回滚
+
+Cloudflare Dashboard -> Workers -> 对应 Worker -> Deployments -> 选择历史版本 Rollback。
+
+数据库变更不会自动回滚。删列、改类型等 migration 必须提前设计回滚或兼容路径。
+
+## 常用命令
+
+```bash
+pnpm exec wrangler hyperdrive list
+pnpm exec wrangler hyperdrive update <id> --connection-string='...'
+pnpm exec wrangler secret put SESSION_SECRET
+pnpm exec wrangler tail --env=test --format=json
+pnpm run deploy:test
+pnpm run deploy
+```
+
+## 故障排查
+
+| 现象                                    | 常见原因 / 处理                                                      |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| `pnpm dev` 后 `/api/*` 401              | edge proxy 拿不到 `SESSION_SECRET`，`.env.local` 也要写同样的值      |
+| `no local hyperdrive connection string` | `wrangler.jsonc` 未配置 `hyperdrive.localConnectionString`           |
+| 登录 200 但列表 401                     | `.env.local` 与 `.dev.vars` 的 `SESSION_SECRET` 不一致               |
+| `openapi.json` 生成失败                 | 先确保 dev server 已运行，端口与生成器配置一致                       |
+| 线上 500 `数据库未初始化`               | Hyperdrive binding id、env 或账号不匹配                              |
+| Worker bundle 超 3 MiB                  | 检查重页面是否动态加载、是否引入了不必要的大依赖                     |
+| 线上 GET 读到旧数据                     | 优先排查 Cloudflare 缓存，API 路径需要明确 `Cache-Control: no-store` |
+
+## 运行时注意事项
+
+- Cloudflare Workers runtime 里同步 env 读取可能早于 binding 注入，API route 中优先使用 async env 读取封装。
+- 后台任务或 `runInBackground` 里不要重新依赖可能为空的同步 env，必要时在请求上下文缓存连接串。
+- `drizzle-zod` 与 Worker 构建偶尔会有运行时兼容问题，复杂 schema 可退回显式 zod object，但要保留类型意图。
+- 自定义域名上的 API GET 可能被 CDN 缓存；对 `/api/*` 添加 no-cache/no-store 是重要保护。
+- 使用 `wrangler tail --env=<env> --format=json` 看真实 Worker 日志，不只依赖本地推断。

package/.agents/skills/nextjs/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: nextjs
+description: Next.js App Router 项目的目录、路由、后端 API、Drizzle schema、OpenAPI 客户端生成和代码组织约定。新增/修改页面、API、DB schema、业务 action、公共 utils 或调整 Next.js 配置时使用。
+metadata:
+  short-description: Next.js 目录、API、DB 与代码组织约定
+---
+
+# Next.js 开发约定
+
+适用于 Next.js 16 App Router + Turbopack 项目。前后端共存在 `app/` 下，通过路由分组隔离运行时边界。
+
+## 目录分组
+
+```txt
+app/
+├── (backend)/        # 后端独占：API 路由 + DB + 服务端 utils
+├── (frontend)/       # 前端独占：页面 + 客户端 utils + 组件
+├── (common)/         # 前后端共享：无运行时依赖的纯逻辑
+├── manifest.ts
+proxy.ts              # Next.js 16 Proxy，原 middleware，API 鉴权入口
+```
+
+路径别名：
+
+- `@backend/*` -> `app/(backend)/*`
+- `@frontend/*` -> `app/(frontend)/*`
+- `@common/*` -> `app/(common)/*`
+- `@/*` -> 项目根
+
+跨 `(backend)` / `(frontend)` / `(common)` 边界 import 必须用别名，禁止相对路径跨边界。
+
+## 放置位置决策
+
+1. 依赖 Node-only API、数据库、环境密钥、`next/server` -> `(backend)`
+2. 依赖浏览器 API、React hooks、antd、`next/navigation` -> `(frontend)`
+3. 前后端都要用且零运行时依赖的类型、常量、纯函数、zod 片段 -> `(common)`
+4. 含糊场景默认留在使用方分组，不要过度抽取
+
+所有函数、工具、辅助逻辑必须放进对应分组的 `utils/`。页面、组件、schema、route 里不要导出工具函数。
+
+## 文件与命名
+
+- 自建文件和目录统一 kebab-case。
+- React 组件导出用 PascalCase。
+- 函数/变量用 camelCase。
+- 常量用 SCREAMING_SNAKE_CASE。
+- hook 文件名用 `use-<name>.tsx`。
+- 路由文件固定 `route.ts`，页面文件固定 `page.tsx` / `layout.tsx`。
+- 私有辅助模块可用 `_helper.ts`。
+
+新建文件时按这个顺序判断：
+
+```txt
+路由 -> app/(backend)/api/<resource>[/子路径]/route.ts
+页面 -> app/(frontend)/admin/<resource>/page.tsx
+仅本页组件 -> 页面同目录 <kebab-name>.tsx
+复用组件 -> app/(frontend)/components/<kebab-name>.tsx
+React hook -> app/(frontend)/hooks/use-<name>.tsx
+后端业务函数 -> app/(backend)/utils/actions/<name>.ts
+后端工具 -> app/(backend)/utils/<topic>/
+前端工具 -> app/(frontend)/utils/<kebab-name>.ts
+共享纯逻辑 -> app/(common)/<utils|types|constants>/
+```
+
+## 单一职责
+
+一个文件只围绕一件事组织，文件名应该能预测文件内容。
+
+- 一个文件只有一个主角。
+- 文件名等于主角名。
+- 文件超过约 150 行、出现两组互不调用的功能、导出超过 5 个不强相关 symbol、import 依赖明显分裂时，优先拆分。
+- 页面目录下的子文件默认私有，只服务该页面。
+- `schemas/index.ts`、`apis/index.tsx`、`generator/`、框架配置文件可以聚合，但聚合文件里不要塞业务逻辑。
+
+## API 路径规范
+
+```txt
+app/(backend)/api/
+├── route.ts                    -> GET /api，OpenAPI 文档
+├── <resource>/
+│   ├── route.ts                -> GET/POST/PUT/DELETE /api/<resource>
+│   └── list/
+│       └── route.ts            -> GET /api/<resource>/list
+```
+
+强制规则：
+
+- 资源名单数、kebab-case：`/api/key`、`/api/api-key`。
+- 列表接口必须是 `GET /api/<resource>/list`，不要把 `GET /api/<resource>` 当列表。
+- 详情接口用 `GET /api/<resource>?id=xxx` 或唯一查询参数，避免 `/api/<resource>/<id>`。
+- 操作类路径用子目录：`/api/key/verify`、`/api/email/code/verify`，不要用 query action。
+- 多级路径必须有父子依赖关系。
+- 标准增删改查尽量放同一个 `app/(backend)/api/<resource>/route.ts`，只有列表固定放 `/list`。
+
+## 后端 API
+
+每个 `route.ts` 用 `next-rest-framework` 的 `route({...})` 组装命名操作，通过解构 HTTP 动词导出。
+
+优先使用 `@backend/utils/route-operation` 的工厂：
+
+- `postOperation`
+- `putOperation`
+- `deleteOperation`
+- `getOperation`
+- `getListOperation`
+
+只有这些场景才手写 `routeOperation`：
+
+- multipart/form-data 上传。
+- upsert 或非标准写入语义。
+- 代理、文件流、非 JSON 响应。
+- 需要完全自定义响应或特殊副作用。
+
+`postOperation` / `putOperation` 支持：
+
+- `setBody(req)`：写入前合入字段，如随机 key、`userId`、租户 id。
+- `onSuccess(data)`：写入成功后的加工或副作用，必须返回最终响应数据。
+- `onError(error)`：定制错误响应；否则交给默认 PG 约束错误翻译。
+
+路由 handler 只做参数验证、组合 action、包装响应；DB 查询和业务逻辑放 `app/(backend)/utils/actions/*.ts`。
+
+## DB Schema
+
+每张表一个 schema 文件：
+
+```txt
+app/(backend)/db/
+├── index.ts
+├── schemas/
+│   ├── <resource>.ts
+│   └── index.ts
+└── migrations/
+```
+
+约定：
+
+- 用 `createTableSchema` 统一产出 `table` + `selectSchema`，并注入公共字段。
+- 用 `createInsertSchema(table)` 生成 insert schema。
+- 用 `queryListSchema(...)` 生成列表查询 schema。
+- `schemas/*.ts` 只定义表和 zod schema，不写查询函数。
+- 新表后在 `schemas/index.ts` 追加 `export * from "./<resource>"`。
+- 每次 schema 变更必须 `pnpm db:generate`，迁移文件必须由命令生成，不手写或手改 migration/meta。
+
+## OpenAPI 与前端 Client
+
+后端 OpenAPI 文档入口在 `app/(backend)/api/route.ts`。
+
+生成流程：
+
+```bash
+pnpm dev
+pnpm openapi:json:generate
+pnpm openapi:client:generate
+```
+
+- `public/openapi.json` 来自运行中的 dev server。
+- `app/(frontend)/apis/generator/` 是 openapi-generator 产物，不手改。
+- 新增 tag 后，在 `app/(frontend)/apis/index.tsx` 追加对应 `XxxApiFactory`。
+
+## 认证入口
+
+`proxy.ts` 统一拦截 `/api/:path*`：
+
+- `publicRoutes` 按 path + method 白名单。
+- Session 通过 `@backend/utils/session` 解密 JWT。
+- API Key 通过 `validateApiKey` 校验。
+- 新路由默认受保护，只有明确需要免登录时才加白名单。
+
+## TypeScript 与代码风格
+
+- TypeScript `strict: true`，显式处理 null/undefined。
+- import 顺序：外部包 -> `@backend/@frontend/@common/@ai0x0/utils` -> 相对路径。
+- 字符串双引号、两空格缩进、末尾逗号。
+- 注释用简短中文说明段落意图，不逐行翻译代码。
+- 错误提示统一走上层错误处理或前端 app bridge，不要 `alert` / 裸 `console.log`。
+- `ai0x0.configs.recommended` 中所有自定义规则都是 `error`，同时开启 `curly: "error"`。
+- 所有 `if` / `for` / `while` / `else` 块必须写花括号，不写单行裸语句。
+- 禁止 `.then()`，Promise 链统一改成 `async/await`。
+- 禁止单字母变量名，`_`、for 循环迭代变量、泛型类型参数例外。
+
+## 禁止 try/catch
+
+业务代码不要写 `try { ... } catch { ... }`。
+
+- 后端错误交给 `next-rest-framework`、`route-operation` 和 `onError`。
+- 前端请求错误交给 axios 拦截器、`useRequest`、app message。
+- fire-and-forget 副作用只允许 `.catch((e) => console.error(...))` 做最终兜底。
+
+允许例外：
+
+- `JSON.parse`、`atob`、第三方无类型库等解析容错。
+- setup/proxy 等框架底层入口需要兜住请求生命周期。
+- 测试中优先用 `expect(...).rejects`，不要额外包 try/catch。
+
+## 禁止散落 `as`
+
+- 不要在业务文件里重复声明 OpenAPI 已生成的 enum union。
+- 前端 enum 使用 generator 导出的 `XxxEnum` 值和 `XxxType` 类型。
+- 禁止散落 `as T`，`as const` 例外。
+- JSONB / unknown 等边界，把断言收敛到命名小帮手，并用 eslint disable 注释说明原因。
+
+## 文件分区
+
+超过约 150 行、或顶层出现多种代码的 `.ts` / `.tsx`，用中文等号分隔块组织：
+
+```ts
+// ==============================================================================
+// 类型 & 常量
+// ==============================================================================
+
+// ==============================================================================
+// 主组件 Xxx：一句话描述职责
+// ==============================================================================
+```
+
+组件体内分区宽度用 76 个等号，常用分区名：`数据请求`、`副作用`、`派生数据 & 小工具`、`操作`、`渲染`。
+
+ESLint 按行数强制分区数量：
+
+- 150 行起至少 1 个分区块。
+- 300 行起至少 2 个分区块。
+- 450 行起至少 3 个分区块。
+- 之后每约 150 行再增加 1 个分区块。
+
+分区块必须是连续三行 `//` 注释，中间行写中文标题，上下行是 4 个以上等号。
+
+## ESLint 规则速查
+
+推荐配置会启用这些强制规则：
+
+- `ai0x0/no-then`：禁止 `.then()`，使用 `async/await`。
+- `ai0x0/no-one-letter-vars`：禁止单字母变量名。
+- `ai0x0/require-section-divider`：大文件必须用等号注释块分区。
+- `ai0x0/no-hardcoded-style`：前端样式值必须走 antd token。
+- `ai0x0/no-antd-space`：禁止 `<Space>` / `<Space.Compact>`，使用 `<Flex>`。
+- `ai0x0/require-use-form`：表单字段状态不能用 `useState` / `useSetState` 管。
+- `ai0x0/require-form-convention`：Form 必须 `onFinish`，字段必须 rules，禁止 Modal.onOk 提交。
+- `ai0x0/require-pro-components`：业务表单优先 ProComponents。
+- `ai0x0/no-use-request-run`：禁止解构 `run`，使用 `runAsync` 并在调用处 `await`。
+- `ai0x0/no-consecutive-setstate`：连续 `setState({ ... })` 要合并成一次。
+
+## 常用命令
+
+```bash
+pnpm exec tsc
+pnpm exec eslint
+pnpm exec eslint --fix
+pnpm db:generate
+pnpm db:migrate
+pnpm openapi:json:generate
+pnpm openapi:client:generate
+```

package/README.md

@@ -17,6 +17,36 @@ Declarative CRUD factories on top of `next-rest-framework`, `drizzle-orm/pg-core
 
 See [SKILL.md](./SKILL.md) for detailed workflow, setup, and escape hatches.
 
+## Agent Skills
+
+This package also ships reusable project skills under `.agents/skills`:
+
+| Skill                 | Covers                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------- |
+| `ai0x0-utils/backend` | CRUD factories, drizzle schemas, route-operation setup, action helpers                            |
+| `nextjs`              | App Router directories, API routes, drizzle schemas, OpenAPI client generation, code organization |
+| `antd`                | Ant Design forms, ProTable, ModalForm, token-based styling, ahooks data flow                      |
+| `cloudflare`          | OpenNext, Cloudflare Workers, Wrangler, Hyperdrive, Neon, deploy and runtime troubleshooting      |
+
+To use them in a project, copy the packaged skills into the project root:
+
+```bash
+cp -R node_modules/@ai0x0/utils/.agents ./
+```
+
+After copying, Codex/agents can load them from `.agents/skills/<name>/SKILL.md`.
+
+If the project already has local skills, copy only the packaged skill folders you need:
+
+```bash
+mkdir -p .agents/skills
+cp -R node_modules/@ai0x0/utils/.agents/skills/nextjs .agents/skills/
+cp -R node_modules/@ai0x0/utils/.agents/skills/antd .agents/skills/
+cp -R node_modules/@ai0x0/utils/.agents/skills/cloudflare .agents/skills/
+mkdir -p .agents/skills/ai0x0-utils
+cp -R node_modules/@ai0x0/utils/.agents/skills/ai0x0-utils/backend .agents/skills/ai0x0-utils/
+```
+
 ## ESLint Rules & Config
 
 ### Plugin (`eslint-rules/`)
@@ -88,3 +118,7 @@ Peer dependencies: `drizzle-orm ^0.45.x`, `drizzle-zod ^0.8.x`, `zod ^4.x`.
 ## Docs
 
 - [SKILL.md](./SKILL.md) — full backend CRUD workflow and API reference
+- [.agents/skills/ai0x0-utils/backend/SKILL.md](./.agents/skills/ai0x0-utils/backend/SKILL.md) — packaged backend CRUD skill
+- [.agents/skills/nextjs/SKILL.md](./.agents/skills/nextjs/SKILL.md) — Next.js project conventions
+- [.agents/skills/antd/SKILL.md](./.agents/skills/antd/SKILL.md) — Ant Design frontend conventions
+- [.agents/skills/cloudflare/SKILL.md](./.agents/skills/cloudflare/SKILL.md) — Cloudflare Workers deployment conventions